/*!
    \copyright  Copyright (c) 2023 Qualcomm Technologies International, Ltd.\n
                All Rights Reserved.\n
                Qualcomm Technologies International, Ltd. Confidential and Proprietary.
    \file
    \defgroup   sensor_subsystem Sensor SubSystem Control
    @{
        \ingroup    sensor_domain
        \brief      Module providing interface for managing the sensor subsystem.

        @startuml
            hide empty description
            UNINITIALISED: Start state
            UNINITIALISED-->OFF : SensorSubsystem_Init(), called from application init table
            OFF-->STARTING : SensorSubsystem_LoadImage()
            OFF: Sensor Subsystem powered off

            STARTING: Load image to sensor subsystem
            STARTING: Start transport(s)
            STARTING-->STARTED: After Sensor Subsystem loaded and started
            note on link: SENSOR_SUBSYSTEM_STARTED_IND sent to client

            STARTED: Sensor SubSystem loaded and running
            STARTED: Transports for ERPC and messages available (if requested)
            STARTED-->OFF : SensorSubsystem_Unregister()
            note on link: SENSOR_SUBSYSTEM_STOPPED_IND sent to client

        @enduml

*/

#ifndef SENSOR_SUBSYSTEM_H_
#define SENSOR_SUBSYSTEM_H_

#include <domain_message.h>


/*! \brief Events sent by the sensor subsystem module */
typedef enum
{
    /*! Requested sensor subsystem image has been loaded successfully 
        This should be used as a trigger to initialise any remote
        procedure calls required
     */
    SENSOR_SUBSYSTEM_STARTED_IND = SENSOR_SUBSYSTEM_MESSAGE_BASE,

    /*! Call to SensorSubsystem_Unregister() has been successful.
        The sensor subsystem has not been powered off, as other
        clients are still registered */
    SENSOR_SUBSYSTEM_UNREGISTER_CFM,

    /*! Sensor subsystem has been stopped */
    SENSOR_SUBSYSTEM_STOPPED_IND,

} sensor_subsystem_msg_t;

/*! \brief Perform basic initialisation of the sensor subsystem module

    This should be called as part of system initialisation.

    \param init_task Unused, part of init table interface
 */
bool SensorSubsystem_Init(Task init_task);

/*! \brief Load and start the sensor subsystem

    Notify the sensor subsystem controller that access to the sensor subsystem
    is required.

    Provide the file that holds the sensor subsystem image.

    The startup flags make it possible to start the sensor subsystem with or
    without the inbuilt messaging and remote procedure call support.

    When the subsystem has started successfully a #SENSOR_SUBSYSTEM_STARTED_IND 
    message will be sent to the init_task.

    Attempts to start the sensor subsystem multiple times will fail.

    The required sequence is 
    \li SensorSubsystem_Init()
    \li SensorSubsystem_LoadImage()
    \li SensorSubsystem_Register()
    \li SensorSubsystem_Unregister()

    Following this sequence, a fresh image can be loaded using LoadImage

    \param init_task The task to send #SENSOR_SUBSYSTEM_STARTED_IND to
 */
void SensorSubsystem_LoadImage(Task init_task, FILE_INDEX file_id, uint32 startup_flags);

/*! \brief Register for sensor subsystem notifications

    Add the client_task to the list of clients.

    If the subsystem has already started successfully a #SENSOR_SUBSYSTEM_STARTED_IND 
    message will be sent immediately to the client_task, otherwise the message
    will be sent when the subsystem has started successfully.

    \param client_task The task to send status indications to
 */
void SensorSubsystem_Register(Task client_task);

/*! \brief Unregister for use of sensor subsystem

    Tell the sensor subsystem controller that access to the sensor subsystem is
    no longer required. The sensor subsystem will be powered off if no cients 
    are registered.

    If this is the last client, then a #SENSOR_SUBSYSTEM_STOPPED_IND will be 
    sent when the subsystem has stopped. If there are remaining clients, a
    #SENSOR_SUBSYSTEM_UNREGISTER_CFM message will be sent to client_task

    \param client_task The task requesting unregister
 */
void SensorSubsystem_Unregister(Task client_task);


/*! \brief Check if Sensor Subsystem ready for communication

    The platform initialisation sends confirmation when the sensor SS
    has started. The messaging starts autonomously after this.

    This function allows the status to be checked.

    If supplied, a message is sent to the supplied task, otherwise
    TRUE or FALSE is returned

    \param response_task Task to send #SENSOR_SUBSYSTEM_CONNECTED_IND
 */
bool SensorSubsystem_CheckReady(Task response_task);

#endif /* SENSOR_SUBSYSTEM_H_ */
/*! @} */